NAZWA¶

semctl - sterowanie semaforami

SKŁADNIA¶

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>

int semctl(int semid, int semnum, int cmd, ...);

OPIS¶

Funkcja semctl wykonuje operację sterującą określoną przez cmd na zestawie semaforów określonym przez semid lub na semnum-tym semaforze tego zestawu. (Numeracja semaforów zaczyna się od 0.)

Funkcja ta posiada trzy lub cztery argumenty. Gdy jest ich cztery, wywołanie ma postać semctl(semid,semnum,cmd,arg), gdzie czwarty argument arg jest typu union semun zdefiniowanego następująco:

#if defined(__GNU_LIBRARY__) && !defined(_SEM_SEMUN_UNDEFINED)
/* union semun jest zdefiniowana w <sys/sem.h> */
#else
/* dla zgodności z X/OPEN musimy sami sobie zdefiniować */
union semun {


      int val;                  /* wartość dla SETVAL */


      struct semid_ds *buf;     /* bufor dla IPC_STAT i IPC_SET */


      unsigned short *array;    /* tablica dla GETALL i SETALL */


                                /* Część specyficzna dla Linuksa: */


      struct seminfo *__buf;    /* bufor dla IPC_INFO */
};
#endif

Dozwolone wartości parametru cmd to:

IPC_STAT

Kopiowanie informacji ze struktury kontrolnej zestawu semaforów do struktury wskazywanej przez arg.buf. Argument semnum jest pomijany. Proces wywołujący funkcję musi mieć prawa do odczytu zestawu semaforów.

IPC_SET

Zapis wartości niektórych pól struktury semid_ds wskazywanej przez arg.buf do struktury kontrolnej zestawu semaforów z jednoczesnym uaktualnieniem pola sem_ctime (tj. przypisaniem mu aktualnego wskazania czasu). Pola zadanej struktury struct semid_ds wskazywanej przez arg.buf, których wartości są kopiowane to:

	sem_perm.uid
	sem_perm.gid
	sem_perm.mode	/* tylko 9 najmniej znaczących bitów */

Efektywny identyfikator użytkownika procesu wywołującego musi wskazywać na administratora systemu, twórcę zestawu semaforów lub jego właściciela. Argument semnum jest pomijany.

IPC_RMID

Natychmiastowe usunięcie zestawu semaforów i związanych z nim struktur danych. Wszystkie procesy oczekujące zostaną wznowione i wywołania, które wykonywały zasygnalizują błąd (przypisując zmiennej errno wartość EIDRM). Efektywny identyfikator użytkownika procesu wywołającego funkcję musi wskazywać na administratora systemu, twórce zestawu semaforów lub jego właściciela. Argument semnum jest pomijany.

GETALL

Zwraca wartości semval wszystkich semaforów z zestawu umieszczając je w tablicy arg.array. Argument semnum jest pomijany. Proces wywołujący funkcję musi mieć prawa do odczytu zestawu semaforów.

GETNCNT

Zwraca wartość semncnt skojarzoną z semaforem numer semnum semaforem (tzn. liczbę procesów oczekujących na zwiększenie się wartości semval skojarzonej z semaforem numer semnum). Proces wywołujący funkcję musi mieć prawa do odczytu zestawu semaforów.

GETPID

Zwraca wartość sempid skojarzoną z semaforem o numerze semnum w zestawie. (jest to identyfikator procesu, który ostatnio wykonał semop na semaforze). Proces wywołujący funkcję musi mieć prawa do odczytu zestawu semaforów.

GETVAL

Zwraca wartość semval semafora o numerze semnum w zestawie. Proces wywołujący funkcję musi mieć prawa do odczytu zestawu semaforów.

GETZCNT

Zwraca wartość semzcnt skojarzoną z semaforem o numerze semnum w zestawie. (tzn. liczbę procesów oczekujących na osiągnięcie przez semafor o numerze semnum wartości 0). Proces wywołujący funkcję musi mieć prawa do odczytu zestawu semaforów.

SETALL

Przypisuje wartości semval wszystkim semaforom zestawu, korzystając z tablicy arg.array, jednocześnie uaktualnia pole sem_ctime struktury semid_ds skojarzonej z zestawem. Wszystkie struktury sem_undo skojarzone z zestawem są we wszystkich procesach zwalniane. Procesy oczekujące na osiągnięcie przez poszczególne semafory określonych wartości są wznawiane, jeśli któraś z wartości semval stanie się zerowa lub wzrośnie. Argument semnum jest pomijany. Proces wywołujący funkcję musi mieć prawa do modyfikacji zestawu semaforów.

SETVAL

Przypisuje wartość arg.val polu semval semafora o numerze semnum w zestawie. Pole sem_ctime struktury semid_ds skojarzonej z semaforem jest uaktualniane. Wszystkie struktury sem_undo skojarzone z semaforem są zwalniane. Procesy oczekujące na osiągnięcie przez semafor określonych wartości zostaną wznowione, jeśli semval stanie się równe zeru lub wzrośnie. Proces wywołujący funkcję musi mieć prawa do odczytu zestawu semaforów.

WARTOŚĆ ZWRACANA¶

W przypadku wystąpienia błędu, semctl zwróci -1, przypisując zmiennej errno wartość określającą rodzaj błędu. W przeciwnym przypadku zwrócona zostanie nieujemna wartość zależna od określonej przez cmd wykonywanej operacji w następujący sposób:

GETNCNT

wartość semncnt.

GETPID

wartość sempid.

GETVAL

wartość semval.

GETZCNT

wartość semzcnt.

Dla wszystkich pozostałych wartości cmd w razie pomyślnego zakończenia zwracane jest 0.

BŁĘDY¶

W przypadku wystąpienia błędu, zmienna errno przyjmie jedną z następujących wartośći:

EACCES

Proces wywołujący funkcję nie ma odpowiednich praw wymaganych do wykonania operacji cmd.

EFAULT

Adres wskazywany przez arg.buf lub arg.array jest niedostępny.

EIDRM

Zestaw semaforów został usunięty.

EINVAL

Niewłaściwa wartość parametru cmd lub semid.

EPERM

Argument cmd ma wartość IPC_SET lub IPC_RMID, ale proces wywołujący funkcję nie ma uprawnień upoważniających do wykonania tego polecenia.

ERANGE

Argument cmd ma wartość SETALL lub SETVAL ale przekazywana wartość semafora semval (dla któregoś z semaforów zestawu) jest mniejsza od 0 lub większa od wartości ograniczenia systemowego SEMVMX.

UWAGI¶

Polecenia sterujące IPC_INFO, SEM_STAT i SEM_INFO są używane przez program ipcs(8) do pobierania informacji o używanych zasobach w systemie. Jeśli zajdzie potrzeba, polecenia te mogą w przyszłości ulec zmianie lub ich obsługa może zostać zawarta w systemie plików /proc.

Niektóre pola struktury struct semid_ds były w Linuksie 2.2 typu short a stały się typu long w Linuksie 2.4. Aby to wykorzystać, powinna wystarczyć rekompilacja pod glibc-2.1.91 lub nowszą. (Jądro rozróżnia stare i nowe wywołania za pomocą znacznika IPC_64 w cmd.)

Dla wywołania semctl obowiązują następujące ograniczenia systemowe:

SEMVMX

Maksymalna wartość semval: zależna od implementacji (32767).

W celu uzyskania lepszej przenośności, najlepiet zawsze wywoływać semctl z czterema argumentami.

Pod Linuksem funkcja semctl nie jest funkcją systemową, ale jest zaimplementowana poprzez funkcję systemową ipc(2).

ZGODNE Z¶

SVr4, SVID. W SVr4 udokumntowano jeszcze EINVAL i EOVERFLOW.

ZOBACZ TAKŻE¶

ipc(2), shmget(2), shmat(2), shmdt(2), ipc(5)